COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	%Start Part 5 of 8 functi.tex
C00030 ENDMK
C⊗;
%Start Part 5 of 8 functi.tex
If {\it function-specifier\/} specifies a generic function that has a
different value for the {\bf :lambda-list} argument, and the new value
is congruent with the lambda-lists of all existing methods or there
are no methods, the value is changed; otherwise an error is signaled.

If {\it function-specifier\/} specifies a generic function that has a
different value for the {\bf :generic-function-class} argument and if
the new generic function class is compatible with the old, {\bf
change-class} is called to change the class of the generic function;
otherwise an error is signaled.

If {\it function-specifier\/} specifies a generic function that has a
different value for the {\bf :method-class} argument, the value is
changed, but any existing methods are not changed.

\label Syntax:

\Defun {ensure-generic-function} {function-specifier\/ \key \vtop{\hbox{:lambda-list}
\hbox{:argument-precedence-order}
\hbox{:declare}
\hbox{:documentation}
\hbox{:generic-function-class}
\hbox{:method-combination}
\hbox{:method-class}
\hbox{:environment}}}
\Vskip1pc!\null
{\it function-specifier\/}::$=$ \curly{{\it symbol\/} $\vert$ {\tt (setf {\it symbol\/})}}

\label Arguments:

The {\it function-specifier\/} argument is a symbol or a list of the
form {\tt (setf {\it symbol\/})}.

The keyword arguments correspond to the {\it option\/} arguments of
{\bf defgeneric}, except that the {\bf :method-class} and
{\bf :generic-function-class} arguments can be class objects
as well as names.

\vfill\eject
The {\bf :environment\/} argument is the same as the {\bf
\&environment} argument to macro expansion functions.  It is typically
used to distinguish between compile-time and run-time environments.

The {\bf :method-combination} argument is a method combination object.

\label Values:

The generic function object is returned.

\label See Also:

{\bf defgeneric}

\endcom


\begincom{find-class}\ftype{Function}

\label Purpose:

The function {\bf find-class} returns the class object named by the
given symbol in the given environment.

\label Syntax:

\Defun {find-class} {symbol {\opt} errorp environment}

\label Arguments:

The first argument to {\bf find-class} is a symbol. 

If there is no such class and the {\it errorp\/} argument is
not supplied or is non-{\bf nil}, {\bf find-class} signals an error.
If there is no such class and the {\it errorp\/} argument is
{\bf nil}, {\bf find-class} returns {\bf nil}.  The default value of
{\it errorp\/} is {\bf t}.

The optional {\it environment\/} argument is the same as the {\bf
\&environment} argument to macro expansion functions.  It is typically
used to distinguish between compile-time and run-time environments.

\label Values:

The result of {\bf find-class} is the class object named by the given symbol.

\label Remarks:

The class associated with a particular symbol can be changed by using
{\bf setf} with {\bf find-class}.  The results are undefined if
the user attempts to change the class associated with a symbol that is
defined as a type specifier by {\it Common Lisp: The Language}.
See the section ``Integrating Types and Classes.''

\endcom


\begincom{find-method}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf find-method} takes a generic function and
returns the method object that agrees on method qualifiers and
parameter specializers with the {\it method-qualifiers\/} and {\it
specializers\/} arguments of {\bf find-method}.  See the section
``Agreement on Parameter Specializers and Qualifiers'' for a
definition of agreement in this context.

\label Syntax:

\Defgen {find-method} {generic-function method-qualifiers specializers {\opt} errorp}

\label Method Signatures:

\Defmeth{find-method} {
\vtop{\hbox{({\it generic-function\/} standard-generic-function)}
\hbox{\it method-qualifiers specializers {\opt} errorp}}}

\label Arguments:

The {\it generic-function\/} argument is a generic function.

The {\it method-qualifiers\/} argument is a list of the
method qualifiers for the method.   The order of the method qualifiers
is significant.  

The {\it specializers\/} argument is a list of the parameter
specializers for the method.  It must correspond in length to
the number of required arguments of the generic function, or
an error is signaled.  This means that to obtain the
default method on a given generic function, a list whose
elements are the class named {\bf t} must be given.

If there is no such method and the {\it errorp\/} argument is
not supplied or is non-{\bf nil}, {\bf find-method} signals an error.
If there is no such method and the {\it errorp\/} argument is
{\bf nil}, {\bf find-method} returns {\bf nil}.  The default value of
{\it errorp\/} is {\bf t}.

\label Values:

The result of {\bf find-method} is the method object with the given
method qualifiers and parameter specializers.

\label See Also:

``Agreement on Parameter Specializers and Qualifiers''

\endcom



\begincom{function-keywords}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf function-keywords} is used to return the keyword
parameter specifiers for a given method.

\label Syntax:

\Defgen {function-keywords} {method}

\label Method Signatures:

\Defmeth {function-keywords} {({\it method\/} standard-method)}

\label Arguments:

The {\it method\/} argument is a method object.

\label Values:

The generic function {\bf function-keywords} returns two values:
a list of the explicitly named keywords and a boolean that states whether
{\bf \&allow-other-keys} had been specified in the method definition.

\endcom


\begincom{generic-flet}\ftype{Special Form}

\label Purpose:

The {\bf generic-flet} special form is analogous to the Common Lisp
{\bf flet} special form.  It produces new generic functions and
establishes new lexical function definition bindings.  Each generic
function is created with the set of methods specified by its method
descriptions.

The special form {\bf generic-flet} is used to define functions whose
names are meaningful only locally and to execute a series of forms
with these function definition bindings.  Any number of such local
generic functions may be defined.

The names of functions defined by {\bf generic-flet} have lexical
scope; they retain their local definitions only within the body of the
{\bf generic-flet}.  Any references within the body of the {\bf
generic-flet} to functions whose names are the same as those defined
within the {\bf generic-flet} are thus references to the local
functions instead of to any global functions of the same names.  The
scope of these generic function definition bindings, however, includes only
the body of {\bf generic-flet}, not the definitions themselves.
Within the method bodies, local function names that match those
being defined refer to global functions defined outside the {\bf
generic-flet}.  It is thus not possible to define recursive functions
with {\bf generic-flet}.

\label Syntax:

\Defspec {generic-flet} {
\vtop{\hbox{\lparen{\rm$\{$}\lparen function-specifier lambda-list
$\lbrack\!\lbrack\downarrow\!$ option $\vert$ \star{method-description} $\rbrack\!\rbrack$\rparen\star{\rm$\}$}\rparen}
\hbox{\star\form}}}
\Vskip 1pc!
{\it function-specifier\/}::$=$ \curly{{\it symbol\/} $\vert$ {\tt (setf {\it symbol\/})}}
\Vskip 1pc!
\settabs\+\hskip\leftskip&\cr
\+&{\it lambda-list\/}::$=$ (&\star{\curly{var}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var\/{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var\/{\rm )}}{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} {\rm )} \cr
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order
\plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{arg\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
%\Vskip 1pc!
\vfill\eject
{\it method-description\/}::$=$ {\tt (:method}
\vtop{\hbox{\it \star{\curly{method-qualifier\/}} specialized-lambda-list\/}
\hbox{\star{\curly{declaration\/ $\vert$ documentation\/}} \star{\curly{form\/}}{\tt )}}}

\label Arguments:

The {\it function-specifier\/}, {\it lambda-list\/}, {\it option}, {\it
method-qualifier}, and {\it specialized-lambda-list\/} arguments are
the same as for {\bf defgeneric}.

A {\bf generic-flet} local method definition is identical in form to the
method definition part of a {\bf defmethod}.

The body of each method is enclosed in an implicit block.  If {\it
function-specifier\/} is a symbol, this block bears the same name as
the generic function.  If {\it function-specifier\/} is a list of the
form {\tt (setf {\it symbol\/})}, the name of the block is {\it
symbol}.  

\label Values:

The result returned by {\bf generic-flet} is the value or values
returned by the last form executed.  If no forms are specified, 
{\bf generic-flet} returns {\bf nil}.

\label See Also:

{\bf generic-labels

defmethod

defgeneric

generic-function}

\endcom


\begincom{generic-function}\ftype{Macro}

\label Purpose:

The {\bf generic-function} macro creates an anonymous generic
function. The generic function is created with the set of methods
specified by its method descriptions.

\label Syntax:

\Defmac {generic-function} {\vtop{\hbox{\it lambda-list}
\hbox{$\lbrack\!\lbrack\downarrow\!$ option $\vert$ \star{method-description} $\rbrack\!\rbrack$}}}
\Vskip 1pc!
\settabs\+\hskip\leftskip&\cr
\+&{\it lambda-list\/}::$=$ (&\star{\curly{var}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var\/{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var\/{\rm )}}{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} {\rm )} \cr
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order
\plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{arg\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip 1pc!
{\it method-description\/}::$=$ {\tt (:method}
\vtop{\hbox{\it \star{\curly{method-qualifier\/}} specialized-lambda-list\/}
\hbox{\star{\curly{declaration\/ $\vert$ documentation\/}} \star{\curly{form\/}}{\tt )}}}

\label Arguments:

The {\it option}, {\it method-qualifier}, and {\it
specialized-lambda-list\/} arguments are the same as for {\bf
defgeneric}.

\label Values:

The generic function object is returned as the result.

\label Remarks:

If no method descriptions are specified, an anonymous generic function with no
methods is created.

\vfill\eject
\label See Also:

{\bf defgeneric

generic-flet

generic-labels

defmethod}

\endcom



\begincom{generic-labels}\ftype{Special Form}

\label Purpose:

The {\bf generic-labels} special form is analogous to the Common Lisp
{\bf labels} special form.  It produces new generic functions and
establishes new lexical function definition bindings.  Each generic
function is created with the set of methods specified by its method
descriptions.

The special form {\bf generic-labels} is used to define functions
whose names are meaningful only locally and to execute a series of
forms with these function definition bindings.  Any number of
such  local functions may be defined.  

The names of functions defined by {\bf generic-labels} have lexical
scope; they retain their local definitions only within the body of the
{\bf generic-labels} construct.  Any references within the body of the
{\bf generic-labels} construct to functions whose names are the same
as those defined within the {\bf generic-labels} form are thus
references to the local functions instead of to any global functions
of the same names.  The scope of these generic function definition bindings
includes the method bodies themselves as well as the body of the {\bf
generic-labels} construct.

\label Syntax:

\Defspec {generic-labels} {
\vtop{\hbox{\lparen{\rm$\{$}\lparen function-specifier lambda-list}
\hbox{\ \ \ $\lbrack\!\lbrack\downarrow\!$ option $\vert$ \star{method-description}$\rbrack\!\rbrack$\rparen\star{\rm$\}$}\rparen}
\hbox{\star\form}}}
\Vskip 1pc!
{\it function-specifier\/}::$=$ \curly{{\it symbol\/} $\vert$ {\tt (setf {\it symbol\/})}}
\Vskip 1pc!
\settabs\+\hskip\leftskip&\cr
\+&{\it lambda-list\/}::$=$ (&\star{\curly{var}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var\/{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var\/{\rm )}}{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} {\rm )} \cr
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order
\plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{arg\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip 1pc!
{\it method-description\/}::$=$ {\tt (:method}
\vtop{\hbox{\it \star{\curly{method-qualifier\/}} specialized-lambda-list\/}
\hbox{\star{\curly{declaration\/ $\vert$ documentation\/}} \star{\curly{form\/}}{\tt )}}}

\label Arguments:

The {\it function-specifier\/}, {\it lambda-list\/}, {\it option}, {\it
method-qualifier}, and {\it specialized-lambda-list\/} arguments are
the same as for {\bf defgeneric}.

A {\bf generic-labels} local method definition is identical in form to the
method definition part of a {\bf defmethod}.

The body of each method is enclosed in an implicit block.  If {\it
function-specifier\/} is a symbol, this block bears the same name as
the generic function.  If {\it function-specifier\/} is a list of the
form {\tt (setf {\it symbol\/})}, the name of the block is {\it
symbol}.  

\label Values:

The result returned by {\bf generic-labels} is the value or values
returned by the last form executed.  If no forms are specified, 
{\bf generic-labels} returns {\bf nil}.

\label See Also:

{\bf generic-flet

defmethod

defgeneric

generic-function}

\endcom




\begincom{initialize-instance}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf initialize-instance} is called by {\bf
make-instance} to initialize a newly created instance.  The generic
function {\bf initialize-instance} is called with the new instance and
the defaulted initialization arguments.

The system-supplied primary method on {\bf initialize-instance}
initializes the slots of the instance with values according to the
initialization arguments and the {\bf :initform} forms of the slots.
It does this by calling the generic function {\bf shared-initialize}
with the following arguments: the instance, {\bf t} (this indicates
that all slots for which no initialization arguments are provided
should be initialized according to their {\bf :initform} forms), and
the defaulted initialization arguments.

\label Syntax:

\Defgen {initialize-instance} {instance {\tt \&rest {\it initargs}}}

\label Method Signatures:

\Defmeth {initialize-instance} {({\it instance\/} standard-object) {\rest} {\it initargs}}

\label Arguments:

The {\it instance\/} argument is the object to be initialized.

The {\it initargs\/} argument consists of alternating initialization
argument names and values.

\label Values:

The modified instance is returned as the result.

\label Remarks:

Programmers can define methods for {\bf initialize-instance} to
specify actions to be taken when an instance is initialized.  If only
{\bf :after} methods are defined, they will be run after the
system-supplied primary method for initialization and therefore will
not interfere with the default behavior of {\bf initialize-instance}.

\label See Also:

``Object Creation and Initialization''

``Rules for Initialization Arguments''

``Declaring the Validity of Initialization Arguments''

{\bf shared-initialize

make-instance

slot-boundp

slot-makunbound}

\endcom


\begincom{invalid-method-error}\ftype{Function}

\label Purpose:

The function {\bf invalid-method-error} is used to signal an error
when there is an applicable method whose qualifiers are not valid for
the method combination type.  The error message is constructed by
using a format string and any arguments to it.  Because an
implementation may need to add additional contextual information to
the error message, {\bf invalid-method-error} should be called only
within the dynamic extent of a method combination function.

%End Part 5 of 8 functi.tex